71.3 自定义Jackson ObjectMapper

在一个HTTP交互中,Spring MVC(客户端和服务端)使用HttpMessageConverters协商内容转换。如果classpath下存在Jackson,你就获取到Jackson2ObjectMapperBuilder提供的默认转换器,这是Spring Boot为你自动配置的实例。

创建的ObjectMapper(或用于Jackson XML转换的XmlMapper)实例默认有以下自定义属性:

  • MapperFeature.DEFAULT_VIEW_INCLUSION,默认是禁用的
  • DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,默认是禁用的

Spring Boot也有一些用于简化自定义该行为的特性。

你可以使用当前的environment配置ObjectMapperXmlMapper实例。Jackson提供一个扩展套件,可以用来关闭或开启一些特性,你可以用它们配置Jackson以处理不同方面。这些特性在Jackson中是使用6个枚举进行描述的,并被映射到environment的属性上:

Jackson枚举 Environment属性
com.fasterxml.jackson.databind.DeserializationFeature spring.jackson.deserialization.<feature_name>=true|false
com.fasterxml.jackson.core.JsonGenerator.Feature spring.jackson.generator.<feature_name>=true|false
com.fasterxml.jackson.databind.MapperFeature spring.jackson.mapper.<feature_name>=true|false
com.fasterxml.jackson.core.JsonParser.Feature spring.jackson.parser.<feature_name>=true|false
com.fasterxml.jackson.databind.SerializationFeature spring.jackson.serialization.<feature_name>=true|false
com.fasterxml.jackson.annotation.JsonInclude.Include spring.jackson.serialization-inclusion=always|non_null|non_absent|non_default|non_empty

例如,设置spring.jackson.serialization.indent_output=true可以美化打印输出(pretty print)。注意,由于松散绑定的使用,indent_output不必匹配对应的枚举常量INDENT_OUTPUT

基于environment的配置会应用到自动配置的Jackson2ObjectMapperBuilder bean,然后应用到通过该builder创建的mappers,包括自动配置的ObjectMapper bean。

ApplicationContext中的Jackson2ObjectMapperBuilder可以通过Jackson2ObjectMapperBuilderCustomizer bean自定义。这些customizer beans可以排序,Spring Boot自己的customizer序号为0,其他自定义可以应用到Spring Boot自定义之前或之后。

所有类型为com.fasterxml.jackson.databind.Module的beans都会自动注册到自动配置的Jackson2ObjectMapperBuilder,并应用到它创建的任何ObjectMapper实例。这提供了一种全局机制,用于在为应用添加新特性时贡献自定义模块。

如果想完全替换默认的ObjectMapper,你既可以定义该类型的@Bean并注解@Primary,也可以定义Jackson2ObjectMapperBuilder @Bean,通过builder构建。注意不管哪种方式都会禁用所有的自动配置ObjectMapper

如果你提供MappingJackson2HttpMessageConverter类型的@Bean,它们将替换MVC配置中的默认值。Spring Boot也提供了一个HttpMessageConverters类型的便利bean(如果你使用MVC默认配置,那它就总是可用的),它提供了一些有用的方法来获取默认和用户增强的消息转换器(message converters)。具体详情可参考Section 71.4, “Customize the @ResponseBody rendering”WebMvcAutoConfiguration源码。